# tools.htmlPlugin

- **Type:** `boolean | Object | Function`
- **Default:**

```js
const defaultHtmlPluginOptions = {
  inject, // corresponding to the html.inject config
  favicon, // corresponding to html.favicon config
  filename, // generated based on output.distPath and entryName
  template, // defaults to the built-in HTML template path
  templateParameters, // corresponding to the html.templateParameters config
  chunks: [entryName],
  minify: {
    // generated based on output.minify
    removeComments: false,
    useShortDoctype: true,
    keepClosingSlash: true,
    collapseWhitespace: true,
    removeRedundantAttributes: true,
    removeScriptTypeAttributes: true,
    removeStyleLinkTypeAttributes: true,
    removeEmptyAttributes: true,
    minifyJS,
    minifyCSS: true,
    minifyURLs: true,
  },
};
```

The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) can be modified through `tools.htmlPlugin`.

:::tip
Rsbuild internally implements HTML-related features based on [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin). It is a fork of [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin), with the same features and options.
:::

### Object Type

When `tools.htmlPlugin` is `Object` type, the value will be merged with the default config via `Object.assign`.

```js
export default {
  tools: {
    htmlPlugin: {
      scriptLoading: 'blocking',
    },
  },
};
```

### Function Type

When `tools.htmlPlugin` is a Function:

- The first parameter is the default config, which can be modified directly.
- The second parameter is also an object, containing the entry name and the entry value.
- The Function can return a new object as the final config.

```js
export default {
  tools: {
    htmlPlugin(config, { entryName, entryValue }) {
      if (entryName === 'main') {
        config.scriptLoading = 'blocking';
      }
    },
  },
};
```

## Disable HTML

Setting `tools.htmlPlugin` to `false` can disable the built-in `html-rspack-plugin` in Rsbuild, and no HTML files will be generated.

```js
export default {
  tools: {
    htmlPlugin: false,
  },
};
```

## Example

### Modify HTML File Name

The `filename` option can be used to modify the file name of the HTML output.

For example, during production builds, a `hash` can be added to the file name:

```js
export default {
  tools: {
    htmlPlugin(config, { entryName }) {
      if (process.env.NODE_ENV === 'production') {
        config.filename = `${entryName}.[contenthash:8].html`;
      }
    },
  },
};
```

### Disable JS/CSS minify

By default, Rsbuild will compresses JavaScript/CSS code inside HTML during the production build to improve the page performance. This ability is often helpful when using custom templates or inserting custom scripts.

However, when `output.inlineScripts` or `output.inlineStyles` is turned on, inline JavaScript/CSS code will be repeatedly compressed, which will have a certain impact on build performance. You can modify the default minify behavior by modifying the `tools.htmlPlugin.minify` configuration.

```js
export default {
  tools: {
    htmlPlugin: (config) => {
      if (typeof config.minify === 'object') {
        config.minify.minifyJS = false;
        config.minify.minifyCSS = false;
      }
    },
  },
};
```
